`co(4,7);──────────────────────────── /// Print Support ───────────────────────────────`co();

                               `keyword(Introduction,/// Introduction);
                           `keyword(Key Structure Elements,/// Key Structure Elements);

 ┌──────────────────────────────────────────────────────────────────────────┐	
 │               `keyword(init_printer,/// init_printer);                `keyword(end_printer,/// end_printer);                    │
 │               `keyword(print_char,/// print_char);                  `keyword(print_data,/// print_data);                     │
 │               `keyword(print_eol,/// print_eol);                   `keyword(print_file,/// print_file);                     │
 │               `keyword(print_screen,/// print_screen);                `keyword(print_str,/// print_str);                      │
 │               `keyword(print_window,/// print_window);                `keyword(realloc_printer,/// realloc_printer);                │
 │               `keyword(set_prt_xlat,/// set_prt_xlat);                `keyword(print_in_bkgrnd,/// print_in_bkgrnd);                │
 └──────────────────────────────────────────────────────────────────────────┘

`co(4,7);─────────────────────────── /// Introduction ─────────────────────────────────`co();

  	These routines are primarily designed for printing to a printer.
	However, printing can be output to a DOS file or device (com1, lpt1,
	tmp.dat, etc).  UltraWin can have as many as four print queues active and
	printing concurrently!  The queuing routines are unique in the fact that
	they can "dynamically" reallocate themselves and "grow" and "shrink" on the
	fly without losing a single byte of data.  The reallocation routines take
	advantage of the lightning fast movmem, as much out of convenience as
	speed.  An 8Mhz 286 can queue 25,000 bytes worth of text strings in one
	second, reallocating every 2048 bytes; really quite remarkable.  The
	output is very fast.  Under normal operation, a "write" occurs on every
	byte, resulting in ~1024 bytes per second (on the same machine).  Not many
	printers can keep up with this speed!  Even greater speed is achieved by
	using "block mode", where each write can output 512 bytes at a time.  This
	is not done by default since outputting to a comm port at a slow baud rate
	could hamper overall performance.

`color(RED,LIGHTGRAY);─────────────────────── /// Key Structure Elements ───────────────────────────`color();

  	Several print structure elements are of importance.  These elements can
	be modified directly for the desired effect.
 	
    The `co(15,1);halt`co(); member controls output from the queue.  If 1, output stops
  and the data in the queue remains unmodified.  If set to 0, output
  continues.

    The `co(15,1);block_mode`co(); member controls the number of bytes output per
  call to the function "print_in_bkgnd".  If 0, only one byte per call will
	be output.  This is useful for communication devices or printers.  If
	outputting to a file or laser printer, setting block mode to 1 will allow
	up to 512 bytes to be output per call, thereby increasing performance.
	This value is defined in UW.H.  Changing this value and recompiling
	UW_PRINT.C will allow you to change the number of bytes sent per block.

		The `co(15,1);xlat`co(); and `co(15,1);xlat_flag`co(); control printer translation.  See `keyword(set_prt_xlat,/// set_prt_xlat);
	for more details.

`co(10,1);/// init_printer`co();   `keyword(source,[UW_PRINT.C]~init_printer);
  	Initializes a printer queue.  Printer queues can be either ram-based or
	disk-based. If ram-based, a queue can be no greater than 64k.  Disk-based
	queues can be up to 2 gigabytes. (Though we have never actually tried this
	size!).  If disk-based, the initial and maximum size should be set to the
	same value, and a second filename is used as a disk buffer.  Be sure that
	the isize and msize values are "long". If any error occurs (file cannot be
	open, memory cannot be allocated,etc) a 0 will be returned.

Prototype:
	int init_printer( char *fname, char *diskbuff, long isize,
										long msize, PRINT *p );

Parameters:
`co(11,1);	char  *fname`co();
		A pointer to a string containing the filename/device to print to.
`co(11,1);	char  *diskbuff`co();
		A pointer to a string containing the filename/device to use as a disk
    buffer.  This is NULL for ram-based queues.
`co(11,1);	long  isize`co();
		The initial size of the print queue. (Maximum 64k if ram based)
`co(11,1);	long  msize`co();
		The maximum size of the print queue. (Maximum 64k if ram based)
		isize and msize should be set equal if using a disk based queue.
`co(11,1);	PRINT *p`co();
    A pointer to a print queue structure.   

Usage:
	PRINT printer1, printer2;
	...
	if( !init_printer("out1.prt", NULL, 2048L, 16384L, &printer1) )
		wn_plst(0,0,"cannot initialize printer", wnp);
	if( !init_printer("out2.prt", "disk.buf", 32768L, 32768L, &printer2) )
		wn_plst(0,0,"cannot initialize printer", wnp);

`co(10,1);/// end_printer`co();   `keyword(source,[UW_PRINT.C]~end_printer);
  	Closes any files and frees any memory used by the print queue.  If
	disk-based, the temporary disk file is left intact so that it will not
	have to be recreated during the next program execution. You may delete
	this file yourself if desired.

Prototype:
	int end_printer( PRINT *p );

Parameters:
`co(11,1);	PRINT *p`co();
    A pointer to a print queue structure.   

Usage:
	PRINT printer1;
	...
	end_printer(&printer1);

`co(10,1);/// print_char`co();   `keyword(source,[UW_PRINT.C]~print_char);
  	Prints a single character. 	A 0 is returned if an error occurs.

Prototype:
	int print_char( uchar c, PRINT *p );

Parameters:
`co(11,1);	uchar c`co();
    A single byte to queue for printing.   
`co(11,1);	PRINT *p`co();
    A pointer to a print queue structure.   

Usage:
	PRINT printer1;
	...
	print_char('\r', &printer1);

`co(10,1);/// print_data`co();   `keyword(source,[UW_PRINT.C]~print_data);
  	Prints a block of data.  A 0 is returned if an error occurs.

Prototype:
	int print_data( uchar *data, int cnt, PRINT *p );

Parameters:
`co(11,1);	uchar *data`co();
    A pointer to the data to queue for printing.   
`co(11,1);	int   cnt`co();
    The number of bytes to print.   
`co(11,1);	PRINT *p`co();
    A pointer to a print queue structure.   

Usage:
	uchar data[132];
	PRINT printer1;
	...
	print_data(data, 132, &printer1);

`co(10,1);/// print_eol`co();   `keyword(source,[UW_PRINT.C]~print_eol);
  	Prints an end-of-line sequence.  The print structure contains two
	variables, "cr_cnt" and "lf_cnt" that control this sequence.  For every
	carriage return "cr_cnt", "lf_cnt" line feeds are printed.
	
		For instance, the simple case of cr_cnt = lf_cnt = 1 outputs \r\n  while
	cr_cnt = 1, lf_cnt = 2 outputs \r\n\n.  A 0 is returned if an error
	occurs.

Prototype:
	int print_eol( PRINT *p );

Parameters:
`co(11,1);	PRINT *p`co();
    A pointer to a print queue structure.   

Usage:
	PRINT printer1;
	...
	print_eol(&printer1);

`co(10,1);/// print_file`co();   `keyword(source,[UW_PRINT.C]~print_file);
  	Prints an entire file.  The file is queued in "raw" format, no CR/LF
	translation occurs.  Make sure that there is enough room in the queue to
	hold the entire file.  A 0 is returned if an error occurs.

Prototype:
	int print_file( char *fname, PRINT *p );

Parameters:
`co(11,1);	char  *fname`co();
		A pointer to a string containing the filename/device to print to.
`co(11,1);	PRINT *p`co();
    A pointer to a print queue structure.   

Usage:
	PRINT printer1;
	...
	print_file("uw_help6.hlp", &printer1);

`co(10,1);/// print_screen`co();   `keyword(source,[UW_PRINT.C]~print_screen);
  	Prints the contents of the entire screen.  A 0 is returned if an error
	occurs.

Prototype:
	int print_screen( PRINT *p );

Parameters:
`co(11,1);	PRINT *p`co();
    A pointer to a print queue structure.   

Usage:
	PRINT printer1;
	...
	print_screen(&printer1);

`co(10,1);/// print_str`co();   `keyword(source,[UW_PRINT.C]~print_str);
  	Prints a single NULL terminated string.  A 0 is returned if an error
	occurs.

Prototype:
	int print_str( uchar *str, PRINT *p );

Parameters:
`co(11,1);	char  *str`co();
		A pointer to the string to print.
`co(11,1);	PRINT *p`co();
    A pointer to a print queue structure.   

Usage:
	PRINT printer1;
	...
	print_string("This is a print string", &printer1);

`co(10,1);/// print_window`co();   `keyword(source,[UW_PRINT.C]~print_window);
  	Prints the contents of the current window.  If the window is bordered
	and the window parameter "inside" is 1, only the inside of the window is
	printed.  If "inside" is 0, the entire window, including the border is
	printed.  A 0 is returned if an error occurs.  Note that this works even
	if the window is overlapped!

Prototype:
	int print_window( WINDOW *wnp, PRINT *p );

Parameters:
`co(11,1);	WINDOW *wnp`co();
		A pointer to the window to print.
`co(11,1);	PRINT  *p`co();
    A pointer to a print queue structure.   

Usage:
	PRINT printer1;
	WINDOW wn;
	...
	print_window(&wn, &printer1);

`co(10,1);/// realloc_printer`co();   `keyword(source,[UW_PRINT.C]~realloc_printer);
  	Is used internally to "grow" and "shrink" ram-based printer queues
	dynamically.  A 0 is returned if an error occurs.

Prototype:
	int realloc_printer( long new_size, PRINT *p );

Parameters:
`co(11,1);	long new_size`co();
		The new size, either greater or less than the current size.
`co(11,1);	PRINT  *p`co();
    A pointer to a print queue structure.   

Usage:
	PRINT printer1;
	...
	realloc_printer(32000L, &printer1);

`co(10,1);/// set_prt_xlat`co();   `keyword(source,[UW_PRINT.C]~set_prt_xlat);
  	Allows translation of the data through a 256-byte translation table.
	For instance, the ASCII data queued can be printed as EBCDIC by pointing
	this to the appropriate table.  Another example would be to point to a
	table that contained ASCII equivalents to the IBM extended characters,
	thereby providing support for older printers that do not support them.
	Note that the translation occurs during output, not during the queuing
	process.

Prototype:
	void set_prt_xlat( int state, uchar *xlat, PRINT *p );

Parameters:
`co(11,1);	int   state`co();
		If 1, the translation table is activated, if 0 it is deactivated.
`co(11,1);	uchar *xlat`co();
		A pointer to the translation table.
`co(11,1);	PRINT  *p`co();
    A pointer to a print queue structure.   

Usage:
	uchar xlat[256];
	PRINT printer1;
	...
	set_prt_xlat(1, xlat, &printer1);

`co(10,1);/// print_in_bkgrnd`co();   `keyword(source,[UW_PRINT.C]~print_in_bkgrnd);
  	Is the "heart" of the printer routines.  It actually scans the printer
	queues and outputs the data to the appropriate file/device. You can call
	this routine as often and as fast as you see fit, or let the idle function
	call it in the "background".  There are no requirements as to when or how
	often this routine is called, but the more frequent the better the printer
	performance.  The total number of bytes output is returned.

Prototype:
	int print_in_bkgrnd( void );

Parameters:

Usage:
	...
	while( !kbhit() )
		print_in_bkgrnd();
OR
	set_idle_func(print_in_bkgrnd);		/* wait event will call this for us */
	do{
			...
  }while(!end);

`co(4,7);───────────────────────── /// Timer/Sound Support ────────────────────────────`co();

  	UltraWin has the additional capability of "taking over" the PC timer
	interrupt.  It does this in a friendly manner by calling the old timer
	vector at the proper rate.  UltraWin increases the timer interrupt rate by
	a factor of 5, or approximately 91 ticks per second.  This allows you much
	finer control over your programs.  We also provide you with an easy to use
	timer facility for taking advantage of these features. UltraWin also
	allows you to sound the PC speaker at a given frequency for a certain
	amount of time and the timer interrupt will turn the speaker off for you.

		It is very important to remember to call end_clock before exiting
	your program.  If you do not, you may experience strange crashes.
  The function `co(11,1);end_video()`co(); calls `co(11,1);end_clock()`co(); to restore the vector and
  clock rate if you forget to make the call.  Taking over the PC timer will
  not affect the PC clock as the original interrupt is still called 18.2
  times per second.  However, if your program or another program that 
  controls your program also takes over the clock and changes the rate you
  may experience some problems.  If this is the case, simply do not call
  `co(11,1);init_clock()`co();.  You will not be able to use the timer variables or
  call `co(11,1);tone()`co(); but `co(11,1);wait_ticks()`co(); will still operate normally.
  
  There are 4 seperate countdown timers available for use in your programs.
  These are simply global variables that are decremented to 0 by the timer
  interrupt.  For instance, to set a countdown timer that will reach 0
  after 1 second, say `co(11,1);Uw_timers[0] = 91;`co(); You can then poll this
  variable at your convenience to determine the time expired.  The
  interrupt decrements the variable by 1 on each tick until the count
  reaches 0, at which time it will remain 0.  The global variables
  `co(11,1);Sys_timers`co(); and `co(11,1);Sound_timer`co(); should not be accessed as these are
  used by UltraWin and its companion product InTUItion.
  
`co(10,1);/// init_clock`co();   `keyword(source,[UW_VID.C]~init_clock);
  	Takes over the PC timer interrupt and sets the timer rate to the desired
	value.                                              

Prototype:
	void init_clock( uint value );

Parameters:
`co(11,1);	uint  value`co();
    The countdown value for the PC timer chip.  0xffff is the standard
    18.2 times per second. 0x7fff would increase the rate by 2, etc.
    
Usage:
	...
 	init_clock(0x3333);											/* speed up by factor of 5 */

`co(10,1);/// end_clock`co();   `keyword(source,[UW_VID.C]~end_clock);
  	Restores the timer interrupt and rate.  Be sure to call this function
	before exiting your program.  `co(11,1);end_video()`co(); will call this for
	you if you forget.

Prototype:
	void end_clock();

Parameters:

Usage:
	...
 	end_clock();
	end_mouse();
	end_video();
	exit(0);
  
`co(10,1);/// tone`co();   `keyword(source,[UW_VID.C]~tone);
  	Sounds the PC speaker at the desired frequency for the desired amount of
	time measured in timer tics. (91/s).  There is no need to turn the sound
	off, this is automatically handled by the timer interrupt.  It is
	perfectly safe to call tone even if a tone is already in progress.  The
	new frequency and time will override the current values.  If you need to
	turn the speaker off before the time has expired you can call `co(11,1);sound_off();`co();

Prototype:
	void tone( uint freq, int dur );

Parameters:
`co(11,1);	uint  freq`co();
    The desired frequency in hertz or cycles-per-second.   
`co(11,1);	int    dur`co();
    The duration of the tone in clock tics (91-per-second).

Usage:
	...
  if( error )
  	tone(1024,9);													/* sound at 1k for 1/10 second */

`co(4,7);───────────────────────── /// Ctrl-C/Ctrl-Break Control ───────────────────────`co();
  
  	UltraWin takes over the Ctrl-C and Ctrl-Break handlers and installs
	a dummy interrupt handler.  In this way, Ctrl-C can be used as any other
	control key.  More importantly, your program will not abort without
	restoring the clock interrupt.  If you need further control over these
	handlers you can modify the ISR's `co(11,1);uw_ctrl_brk();`co(); and `co(11,1);uw_ctrl_c()`co();.
	To prevent the bios from displaying ^C, UltraWin also takes over the
	keyboard interrupt.  When a Ctrl-C or Ctrl-Break is seen, it is replaced
	with a dummy code, 0x1e, which is later remapped back to Ctrl-C by
	check_key.  This is all very confusing but necessary for proper handling.
	The important thing to remember is that the user cannot "accidently"
	break out of your program, yet you can capture these keystrokes and
	exit normally if desired.

`co(4,7);──────────────────────────── /// Debugging Support ───────────────────────────`co();

                        `co(15,?);New "Source Trace" Libraries!`co();

    UltraWin V2.5 adds powerful debugging facilities.  The libraries now
	come in two "flavors", the smaller standard production libraries, and the
	new `co(15,?);Source Trace`co(); libraries.  The Source Trace libraries are used for
	development, and the standard production libraries for the finished
	product.
  
    When using the Source Trace libraries, UltraWin will check the validity
	of most function parameters.  The most important of these are pointers to
	UltraWin's structures; WINDOW, PRINT, and MENU.  UltraWin can detect when
	you pass an invalid or uninitialized pointer to a function and will popup
	an error window stating the function that detected the error and the
	invalid pointer.  You can choose to exit the program in a safe and orderly
	manner, or continue.  If you continue, do so at your own risk; you may
	merely overwrite data on the screen, but you may also write over memory
	outside of your program space and cause all sorts of nasty things, a
	"lockup" being the least of these!
  
    UltraWin also checks many other parameters, such as cursor positioning,
	border styles, window size, etc.  If a problem is detected, the error
	window will appear.  This is even true for UltraWin window macros!  The
	window macros that are used for many UltraWin operations are replaced with
	functions in the Source Trace versions of the library.  This gives you
	parameter validation for what normally is handled by the preprocessor.
  
    The error window shows a call log that displays the last 64 UltraWin
  functions, the file and line number where they where called, and a count
  of how many times they were called.  A call stack shows the internal calls
  made by UltraWin.  For instance, if wn_plst calls mv_cs and mv_cs detects
  and reports the error, the call stack will show that wn_plst called mv_cs.
  mv_cs will not be placed in the call log since it was not called by your
  program.  You can use the cursor keys to scroll up and down through the
  call log.  The top entry (entry 1) is the oldest.  Even more exciting
  than the call log is the fact that the error window can even display
  the offending line in your source code!

    If you choose to exit when an error occurs, UltraWin will call exit(0).
	exit() will close all open files, including files you have opened, and
	will call all functions that are "registered" using atexit().  This
	function allows you to "register" functions to be called by exit and is an
	excellent cleanup technique.  Refer to you compiler's documentation for
	further details.  UltraWin registers the end_video(), end_clock(), and
	end_mouse() functions that correspond to init_video(), init_clock(), and
	init_mouse().  These are all called automatically if you exit.

    To use the Source Trace libraries, simply link in the appropriate
	library for your compiler, and define SOURCE_TRACE at the top of your "C"
	file, before the inclusion of "uw.h".  Most compilers will allow you to
	define it globally for a project, or at least give you the ability to
	define it on the compilers command line.  Defining SOURCE_TRACE allows the
	error window to display the line number of the file, the name of the file
	in which the error was found, and even "pull up" the offending line from
	the "C" file, if it is found in the current directory!  If you do not
	define SOURCE_TRACE, but use the Source Trace version of the library, then
	the error reporting will still be active, but no line number or file
	information will be displayed and macro parameters will not be checked.

    When you are satisfied with your program, it is recommended that you
	relink with the standard production library.  This will reduce code size
	and increase performance.

`co(4,7);──────────────────────── /// Library Naming Conventions ──────────────────────`co();

    UltraWin supports many different compilers, and now with the Source Trace
  feature the number of possible libraries has multiplied greatly.  To
  make it easier to know which library goes with what compiler, we have
  adopted a simple library naming convention.
  
    The first two letters of the library indicates the product, and are the
  letters `co(15,?);UW`co(); for UltraWin.  The next letter(s) indicates the compiler,
  as shown below:

    Compiler                Letters
    ─────────────────────   ────────   
    Turbo C                 `co(15,?);T`co();
    Turbo C++               `co(15,?);TCP`co();
    Borland C               `co(15,?);B`co();
    Borland C++             `co(15,?);BCP`co();
    Microsoft C             `co(15,?);M`co();
    Microsoft C++           `co(15,?);MCP`co();
    Mix Power C             `co(15,?);X`co();
    Zortech C               `co(15,?);Z`co();
    Zortech C++             `co(15,?);ZCP`co();

  The next letter indicates the library model, and is:

    Model                   Letter
    ─────────────────────   ────────   
    Small                   `co(15,?);S`co();
    Medium                  `co(15,?);M`co();
    Compact                 `co(15,?);C`co();
    Large                   `co(15,?);L`co();

  Finally, if the library is a Source Trace "debug" version, the letter `co(15,?);D`co();
	is appended.
  
    For example, the large model standard production library for Turbo C
	would be `co(15,?);UWTL.LIB`co();, the small model Source Trace library for Turbo C would
	be `co(15,?);UWTSD.LIB`co();, and the compact model Source Trace library for Borland C++
	would be `co(15,?);UWBCPCD.LIB`co();.

